Major Workshop Application for ABLE 2022

Application Checklist

Application is a PDF or MS Word document that includes:

  • Workshop title and name(s)of presenters
  • Abstract describing the proposed workshop (300 words maximum)
  • Participant handouts (see note to reviewers below)
  • A list of equipment and supplies needed for a class of 25 students
  • Notes for the Instructor (will be completed post-workshop)
  • Sample results (available from workshop repository)
  • A description of how you will present the laboratory to conference participants
  • Student/TA evaluations of this exercise as a learning experience (not applicable)
  • Application deadline: November 30th.

Notes to the Reviewers

  1. I think the current title of the workshop is NOT the best one to attract participants. I would greatly appreciate your suggestions for improving it.

  2. To show the versatility of Markdown, I composed the handouts for this workshop in a Markdown document, then converted it to MS Word for final formatting and submission. The original “.md” file is available to participants from this workshop’s ABLE 2022 GitHub repository.



Major Workshop Proposal

Title: Using Markdown and Free Online Tools to Write, Publish, and Share an Open-Source Scientific Writing Guide

Presenter

A. Daniel Johnson, Wake Forest University, Department of Biology, 1834 Wake Forest Road, Winston-Salem NC 27109, USA.

Abstract

Scientific writing helps students learn to state problems and claims precisely, summarize evidence to support those claims, and explain their reasoning. At the 2021 ViABLE conference we presented our “six elements model” for teaching scientific writing in multi-section introductory biology courses. One of the essential elements is a standardized Scientific Writing Resource Guide that students and instructors use across multiple courses. Our Resource Guide now is available as an open-access book.

To make our Guide easier to maintain and for others to convert to their preferred formats, we wrote it using Markdown. This lightweight markup language is ideal for writing lab documents; authors can write their text once, then output it in multiple formats such as HTML5 for web pages, or Word documents for handouts. Groups of Markdown files can be converted to interactive online books. Markdown takes ~20 minutes to learn, and marked text remains readable.

Participants in this workshop do not need any technical skills beyond basic computer skills. They will learn to use Markdown by editing our Guide and by creating new pages that they will convert into formatted Word and HTML5 documents. We will demonstrate how to use R Studio to assemble collections of Markdown documents into books, and how to use GitHub to manage and share writing project files.

Participants will leave with a copy of our Scientific Writing Resource Guide that they can revise to match their course requirements, tools for writing and converting Markdown files, and a GitHub account where they can back up their project. Those interested can learn how to launch new book projects of their own, or contribute to our published edition of the Resource Guide.

Keywords: scientific writing, writing guidelines, Markdown, lab development tools, R Studio, web publishing



Introduction

The Scientific Writing Resource Guide

Scientific writing helps students learn to state problems and present claims precisely, summarize evidence to support those claims, and explain their reasoning. For many years, our Scientific Writing Resource Guide has been one of our essential tools for teaching scientific writing in multiple courses. The Guide focuses on writing a lab report that models a journal article because the same components are used in most other forms of scientific communication too. The general format conforms to the Council of Science Editors (8e) standards, with some modifications to make writing easier for students just starting out. The Guide includes sections on data visualization, basic biostatistics, and how to cite literature.

In 2021 we updated, expanded, and published our Writing Resource Guide. Our goal is to support two audiences: undergraduates learning the craft of scientific writing, and biology instructors who either teach scientific writing to undergraduates or supervise teaching assistants who do. Rather than try to make one guide meet the needs of every possible audience, we designed ours to be an evolving resource, and released it under terms of a Creative Commons BY-NC-SA 4.0 license. The Guide is written in Markdown, so users can convert the Guide to whatever format is needed. Participants in this workshop will learn how to access and modify the Resource Guide using free tools. They can edit, extend or modify our Guide as needed to fit their particular needs and requirements, so long as they attribute its original source and do not use it commercially.

Using Markdown For Writing Lab Documents

Producing the shared Resource Guide introduced us to Markdown, a lightweight markup language that is extremely easy to use, and ideally suited to the challenges of writing lab documents that may have to go to multiple destinations. With Markdown, authors write a text once then convert it into multiple file formats. It takes less than 20 minutes to learn most of the Markdown syntax needed for routine writing tasks, and marked-up text is still easy to read. Markdown can be converted to HTML5 so it plays well with most LMSs. It also can be converted directly into MS Word or PDF documents. With additional free tools, collections of Markdown documents can be compiled into interactive online books.

To demonstrate the versatility of Markdown, all of the handouts for this workshop were written in Markdown, then converted it to MS Word for final formatting and submission. The original “.md” file is available to participants from this workshop’s ABLE 2022 GitHub repository.

About This Workshop

Participants in this workshop do not need any technical skills beyond basic computer skills. The exercises assume no prior knowledge of Markdown, the other tools, or computer coding.

Before the workshop participants will need to install GitHub Desktop and register for a free GitHub account. Participants also need to install R and R Studio. We will troubleshoot any installation problems at the start of the workshop.

In the first half of the workshop participants will copy a repository containing our Resource Guide to their personal GitHub account. Then they will create and edit new Markdown documents using R Studio, and a plain text editor. Finally they will push their new files to their personal repository. In the second half of the workshop, participants will learn how to use R Studio and standalone tools to render edited pages into HTML and MS Word formats. I will demonstrate how R Studio plus Bookdown can turn a collection of Markdown files into a book that can be hosted online or printed.

Participants will leave this workshop with a complete copy of the Science Writing Resource Guide that they can revise to match their local needs, editing tools, and a personal GitHub account from which to share work with others, or launch a book project (say, a new lab manual) of their own. Participants will help us identify what additional topics should be included in the Resource Guide, and if interested, contribute new material for the Guide.



Pre-Workshop Assignment: Install the Required Software

Give yourself enough time to install the software. GitHub Desktop takes 10-15 minutes to install. Registering for a new GitHub account takes 5-10 minutes. R Studio Desktop takes 10-15 minutes to install if you do not have it already.

If any installation does not work, we will troubleshoot it at the beginning of the workshop.

Install GitHub Desktop

GitHub is a no/low cost, secure collaboration and code sharing site that is popular with data scientists and developers. GitHub also is becoming a popular hub for hosting blogs, static websites, and e-books (for example, Using Markdown inside R.) GitHub Desktop greatly simplifies installation, creating an account, and handling repositories.

Go to GitHub and follow their instructions for installing GitHub Desktop on your computer: Downloading and Installing GitHub Desktop

If you have time, take a look around the application: Getting Started With GitHub Desktop

Register for a Free GitHub Account

GitHub Desktop should ask if you want to log into an existing account, or create a new one. If it does not do that automatically, go to the GitHub home page and follow the prompts to register. You do not need a private account for this workshop. If you choose to start using GitHub regularly, a private account costs $50/year. GitHub definitely is a good investment; the backup service alone saved me several times when I accidentally deleting important files.

Install R and R Studio Open Source Edition

You need to download and install R (the engine) before R Studio Desktop (the user interface) on your computer.

  1. Download and install R.
    • If you are a Windows user: Click on “Download R for Windows”, then click on “base”, then click on the Download link.
    • If you are macOS user: Click on “Download R for (Mac) OS X”, then under “Latest release:” click on R-X.X.X.pkg, where R-X.X.X is the version number. For example, the latest version of R as of November 25, 2019 was R-3.6.1.
    • If you are a Linux user: Click on “Download R for Linux” and choose your distribution for more information on installing R for your setup.
  2. Download and install R Studio.
    • Scroll down to “Installers for Supported Platforms” near the bottom of the page.
    • Click on the download link corresponding to your computer’s operating system.

For more detailed instructions, consult Installing R and R Studio, Step by Step



Exercise 1: Copying the Resource Guide Repository From GitHub

Background

GitHub stores collections of files related to one project in folders called repositories (aka, “repos”). When you installed GitHub, you created a dedicated spcace inside your computer for storing repositories. This is where your working copy of the Writing Resource Guide lives.

Users can create multiple repositories for different projects. Private repositories can only be seen by their owner and the GitHub users that the project owner specifies. Public repositories are available for anyone to view or copy, but they cannot add new files, or revise or remove existing files without the repository owner’s express permission.

What makes GitHub so useful is that you can make a copy of any repository you have rights to see and store it in your own GitHub account. Your copy contains all of the files that were in the project’s original repository.

There are two kinds of copies: clones, and forks. A clone is a completely independent copy. GitHub will tell you if there have been changes made to the original source repository, but those changes are not added to your copy, and any changes you make to your version do not affect the source. We usually clone repositories when we want to use the materials independently from their original authors.

A fork is a repository copy that remains connected to its parent. All of the users are working collaboratively on the same set of files at the same time. Unlike a Google document though, changes made by collaborators have to be approved by the owner of the repository. Once changes are approved, they are merged into the repository and “pushed” to all collaborators’ copies of the repository. Forked repositories are useful when multiple authors are working on one project. Every change is documented along with who made it. Individuals can work on separate files (and even different versions of the same file) without interfering with each other. Earlier versions of every file are available from the file archive.

In this exercise you will be cloning the ABLE 2022 Workshop repository. This is your sandbox copy; you cannot damage the original source files. You can edit any page or add new pages. If you make a mistake in a document and cannot fix it, just download a new copy. Later you will fork the SWP Writing Resource Guide. You’ll also be using the Commit and Push commands. Do not worry about what they mean right now; we will talk in detail about them in Exercise 3.

Procedure

  1. Use a web browser to log into your GitHub account.

  2. Click on the URL (or type it in) to go directly to the ABLE workshop repository: https://github.com/adanieljohnson/ABLE_2022_Workshop. Alternatively, go to GitHub, look forthe Search window at the top left, and enter adanieljohnson/ABLE_2022_Workshop. This is the shortcut to the project repository.

  3. What you see will be something similar to the screenshot below. Click on “Code” to open the window with the link to clone this repository.

Main page of ABLE Workshop repository


  1. Copy the URL, and paste it somewhere. You will need it in the next steps.

Orange arrow marks the URL to clone the repository.


  1. Open GitHub Desktop. Go to File > Clone Repository.

GitHub Desktop


  1. Paste the URL you just copied into the window. Do not change the local path right now.

 


  1. You should now have a copy of the files on your local hard drive. Use “View in Finder” to double-check.


  1. Before continuing, you want to save your new repository and files to your GitHub account. On the main page of GitHub Desktop, you should see a list of files that have changed since they were last saved to your account. Give your update a SHORT name (yes, “Update” is fine.) Then click on Commit to formally save the changes locally.

Committing changes to your local copy of the files.


  1. To upload a permanent copy in your GitHub account, click on Push to origin.

Pushing a copy of your changes to your main GitHub account


  1. Now that your repo is saved, we can play. Open the folder named Sample Files. It contains several .md files and the corresponding rendered HTML and MS Word formats. Open one of the .md files, pen them, then open the corresponding file with the .md extension.

  2. Using Handout for Exercise 1 as your “.md to .html/.docx dictionary,” try to translate the markup in the .md files.

    • How hard or easy is it to read the original text in the .md file?
    • How does the markup translate into a web page?
    • How does the marked up text translate into a Word document?

  3. If you make any changes to your .md files, be sure to commit them before going on to Exercise 2.



Handout for Exercise 1: Introduction to Markdown

Markdown Syntax

Markdown was created as a way for writers to mark up text quickly to show formatting without having to embed full HTML tags. The goal with Markdown is to separate the structure of a document (headers, paragraphs, bullets, etc.) from the words of the text. By using a single set of marking conventions (called the syntax) marked-up text can be converted to dozens of different formats.

Here is some text formatted so you can see the the markup:

### Level 4 Header - Formatting

There are two main kinds of text formatting:
* Inline formatting (\_italics\_, subscripts like H\~2\~SO\~4\~, etc.)
* Block- or paragraph-level formatting (headings, sub-headings, etc.)

…and what the same text looks like rendered:

Level 4 Header - Formatting

There are two main kinds of text formatting:

  • Inline formatting (italics, subscripts like H2SO4, etc.)
  • Block- or paragraph-level formatting (headings, sub-headings, lists, etc.)

Markdown Codes for Inline Formatting

The table shows how to mark text, and what it will look like when rendered.

Inline Formats How to Mark Them How They Appear
Italics _italicized_ word italicized word
*italicized* word italicized word
Bold __bolded__ word bolded word
**bolded** word bolded word
Bold Italics ___marked___ word marked word
***marked*** word marked word
Superscripts Super^script^ed letters Superscripted letters
Subscripts Sub~script~ letters Subscripted letters
Horizontal rule *** Draws a line across page _____
Inline code (not rendered) `code block` code block
Escape a special character \*code block\* *code block*
Links to web pages [text](link) RStudio
Links with URL [link](link) https://www.rstudio.com
Links to embed local images ![alt text or image title](path/to/local_image). ![Image on my desktop](/home/desktop/image_on_desktop.png)
Links to embed image from web ![alt text or image title](https://upload.wikimedia.org/ wikipedia/commons/thumb/6/6c/ Biology_students_in_lab. jpg/320px-Biology_students_in_lab.jpg). Image on Wikimedia Commons

Codes for Block Level Formatting

Headers

Header levels are indicated with 1-6 hash marks followed by a space.

Block Formats How to Mark Them
Level 1 Header # Level 1 Header
Level 2 Header ## Level 2 Header
Level 3 Header ### Level 3 Header
Level 4 Header #### Level 4 Header
Level 5 Header ##### Level 5 Header
Level 6 Header ###### Level 6 Header

How they render:

Level 1 Header

Level 2 Header

Level 3 Header

Level 4 Header

Level 5 Header
Level 6 Header

Paragraphs

Regular paragraphs need to be separated by a blank line, or they will run together. For example, a text written without spacing lines like this:

    There are several kinds of text formatting to explore.
    Inline formatting text.
    Block- or paragraph-level formatting.
    Lists and quotes.

Looks like this when rendered:

There are several kinds of text formatting to explore. Inline formatting text. Block- or paragraph-level formatting. Lists and quotes.

Text written WITH spacing lines like this:

    There are several kinds of text formatting to explore.

    Inline formatting text.

    Block- or paragraph-level formatting.

    Lists and quotes.

Renders like this:

There are several kinds of text formatting to explore.

Inline formatting text.

Block- or paragraph-level formatting.

Lists and quotes.


Blockquotes are written after the “>” symbol. This text:

> "I thoroughly disapprove of duels. If a man should challenge me,
  I would take him kindly and forgivingly by the hand and lead him
  to a quiet place and kill him."
>
> --- Mark Twain

Renders like this:

“I thoroughly disapprove of duels. If a man should challenge me, I would take him kindly and forgivingly by the hand and lead him to a quiet place and kill him.”

— Mark Twain

Blocks for writing code that is not converted are written between three backticks. To include literal backticks, use more backticks outside.

``` Block of text or code that should NOT be rendered, like this __bold__ word. ```

Hidden Comments

There are two ways to add comments to Markdown that will not display in the rendered text:

[//]: # (This comment in Markdown gets removed from both .html, and .docx)

<!--- This comment in Markdown is retained in .html, gets removed from .docx-->

Lists

Bulleted or unordered lists need to be separated from the preceding paragraph by a blank line. The items start with *, +, or -, and you can nest one list within another list by indenting the sub-list by four spaces. For consistency, it is best to make it a habit of using one character for main bullets, and the other two for sub-bullets.

A coded list looks like:

* First item
* Second item
    + First sub-item
        - First sub-sub-item
        - Second sub-sub-item
    + Second sub-item
* Third item

The output renders as:

  • First item
  • Second item
    • First sub-item
      • First sub-sub-item
      • Second sub-sub-item
    • Second sub-item
  • Third item

Ordered list items start with numbers, but the rule for nesting are the same as for unordered lists.

1. First item
2. Second item
    1. First sub-item
        1. First sub-sub-item
        2. Second sub-sub-item
    2. Second sub-item
3. Third item

The output renders as:

  1. First item
  2. Second item
    1. First sub-item
      1. First sub-sub-item
      2. Second sub-sub-item
    2. Second sub-item
  3. Third item

The two formats can be mixed together:

1. First item
    + Sub-item
    + Sub-item
2. Second item
3. Third item

Renders as:

  1. First item
    • Sub-item
    • Sub-item
  2. Second item
  3. Third item

The challenge when using numbered lists in Markdown is that they sometimes default to starting with #1. There is no simple and consistent way to force a list to start with a particular number. I usually fix this by editing the HTML or Word document directly, or just pre-number lists myself.

Task Lists

Task lists are unordered lists with editable checkboxes instead of bullet marks. To create a task list with open check boxes, begin each item with a dash, space, then opening and closing square brackets separated by one space (- [ ] ) in front of task list items. To select a checkbox, add an x in between the brackets (- [x] ).

How to enter it:

- [x] Write the manual pages
- [ ] Update the LMS
- [ ] Email students

The rendered output looks like this:

  • Write the manual pages
  • Update the LMS
  • Email students

Math Expressions

Inline LaTeX equations are written using standard LaTeX syntax, and enclosed by pairs of $ signs. This code:

$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$

Renders an inline version of the equation as:

\(f(k) = {n \choose k} p^{k} (1-p)^{n-k}\)

Equations in display style are written with a pair of double dollar signs. This code:

$$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$$

Renders as:

\[f(k) = {n \choose k} p^{k} (1-p)^{n-k}\]

The first link below is for a tutorial on writing LaTeX equations. The second link is for a web page where you can write LaTeX equations using an online visual editor.

MS Word handles equation rendering well, but other Markdown formatting tools sometimes fail to render correctly. Always check any formatted equations you have in a .md file the first time you try out a new rendering tool. In practice, we usually do not need to edit equations after typing them the first time. So I usually will render them once, take a screen shot, and embed them as images. As with other steps, what keeps your workflow simple is what you should do.

Handy HTML Bits

There are some things that base Markdown does not handle well. For example, subscript and superscript markup may not work on the first character or number in a word (like 3H) or for a whole word. Some other useful items are not in the GHFM syntax at all. You can fill in these gaps with a few basic HTML codes.

If you need to… Insert this HTML snippet For this result
Force a superscript for a whole word or first character <sup>super</sup>script superscript
Force a subscript for a whole word or first character <sub>sub</sub>script subscript
Strike through text <strike>This</strike> word This word
Add an extra space between items &nbsp;
Add an extra line between items <br>
Add a horizontal rule between lines <hr/> _____
Add Greek letters &alpha;, &eta; α, η

This page is a good source for other HTML shortcuts. You csan find more information about special symbols here.

Learning More

These web resources can help you build your Markdown writing skills. More are listed in the Notes for Instructors.



Exercise 2: Creating and Editing Markdown Pages

Background

Markdown was designed to be easy to add while writing. Unlike HTML, Markdown does not require any special code or starting text at the beginning of a new document. The only requirement is that the saved text file should have .md as the extension.

There are many ways to write Markdown files. You can:

  • Write them entirely inside R Studio. R Studio is a very good plain text editor. If you plan to manage your files entirely through R Studio, it makes sense to write your text files there too. Both R Studio and the next option require you to commit and push changes to GitHub from time to time.
  • Use a separate plain text editor on your computer. If you need to share your documents in many different places or formats, or are not sure where they will go, writing them in a standalone text editor is probably easiest.
  • Write text files inside GitHub via a browser. If you want to be 100% sure you never lose a single word, and don’t mind a few extra steps, writing directy in GitHub might be best. Files written in GitHub via a browser are saved immediately to their repository: no pulling or pushing needed.

Which will work best for you depends on your personal preferences, and how you plan to use the files. You may end up using some of all three methods. Our goal today is to introduce you to each method, so you can find a workflow that fits how you use documents most often.

Personal Tidbit: right now, most of my writing ends up on our campus LMS so it needs to be plain HTML. I write occasional handouts that need to be in MS Word (.docx) format. I prefer to write drafts in a commercial plain text editor that shows Markdown codes in color. I work across multiple computers, so even my early draft files go into a GitHub repository. That way I can access them anywhere.

When it is time to generate output, the commercial text editor I use can convert Markdown directly to plain HTML that I then can copy/paste straight into our LMS. I use R Studio to generate MS Word documents and online books. I rarely make PDFs anymore because they can be hard for screen readers to translate.

In this exercise you will try writing and editing Markdown texts using R Studio as a text editor, and a standalone text editor.

Procedure:

The goal of these two procedures is for you to experience for yourself how Markdown behaves in different editing environments. Usually one will feel more comfortable than the other; that is the way you should start out building your editing workflow.

Editing Markdown Using R Studio

  1. Open R Studio, and choose__File > Open__ and navigate to the ABLE 2022 Workshop repository. Open to the file containing the Table of Contents page for the Writing Resource Guide.

  2. Find 1-2 EXISTING pages you think you might want to edit or contribute to. Also find 1-2 topic that you do not see in the current pages that you think should be in the Guide.

  3. Now open the folder named Writing Resource Guide. It contains the Markdown files (with the “.md” extension) for the full Writing Resource Guide. Locate one of the pre-existing .md files you wanted to edit, and open it.

    • First look at the current structure. If needed, compare it to the markup guide in the handout from earlier. Do you see how the structure of the rendered file is encoded in the Markdown tags? (Remember, you can click the Preview tab at the top of the window to switch from Code to Preview modes.)
    • Look for a section you want to edit. Make some changes, save, then see how your changes look using Preview mode.

  4. Next you will start a new file. Choose File > New File > Markdown file.

Start a new .md file


  1. Enter some starting text. One or two words is enough.

  2. Save the file in your ABLE 2022 Workshop repository. Give your file a name that reflects the topic you did not see. Include the .md extension. TIP: when you name files, do not include spaces. Write all file names in CamelCase (FileName1.md) or Snake_Case (File_Name_1.md)

  3. Now you have a starting file that you can edit any way you wish.

    • If you want to see how changes to the Markdown code affect it, click the Preview button at the top of the window.
    • If the .md file will not display, you probably have an error in the format. Look at the bottom of the page for a tab called R Markdown. There usually is an error message telling you what went wrong.

  4. When you are finished editing your two pages, save them both in the ABLE 2022 Workshop respository folder.

  5. Close R Studio for now.

Editing Markdown Using a Plain Text Editor

  1. Navigate to the your ABLE 2022 Workshop repository folder. Usually it is located in your Documents folder.

  2. Click on one of the .md files in the Writing Resource Guide folder to select it. This time you want to open the file in a plain text editor.

    • For Windows, the default installed text editor is Notepad++.
    • For MacOS, TextEdit is the default installed editor.
    • You can open and edit .md files with any text editor you have installed, such as (Atom, Brackets, Bluefish, BBEdit, etc.)
    • If you have no idea what text editor you have installed, just double-click the file. Your operating system will try to open the file with the appropriate program.

  3. After you have edited an existing .md file, try creating a new one from scratch. Once again, create a new file for a topic you think is missing from the Table of Contents of the Resource Guide.

  4. When you have finished, save both of your edited .md files.

OPTIONAL: Writing Directly in GitHub

The workflow for creating and editing .md files in a browser is a bit different. These instructions only work when you are online and logged into GitHub.

  1. In a browser, log into GitHub (not Desktop). Go to the repository containing your cloned copy of the Resource Guide. At the top of the list, click on Add file. Choose Create new file.

  2. Give your file a name that reflects the topic you did not see. Include the .md extenstion.

  3. Enter some starting text. One or two words is enough.

  4. At the bottom of the page is the Commit dialog. GitHub requires you to describe what you did when you save a file. That information goes in the first box, and is required. It might seem like extra trouble at first, but when you are making changes in critical files, these commit comments can help you track what changes you made and when. If there are multiple authors working on a file, each author’s changes should say specifically what they worked on.

  5. Commit the file directly to the master (branches and pull requests are not important until you are working on more complex projects.) TIP: when you name files, do not include spaces. Write all file names in CamelCase (FileName1.md) or Snake_Case (File_Name_1.md)

  6. Now you have a starting file that you can edit any way you wish. If you want to see how changes to the Markdown code affect it, simply click the Preview tab at the top of the window.

  7. Next, go back to the Table of Contents and find a page you think you might want to edit. Locate the corresponding pre-existing .md file, and open it.

    • First look at the current structure. If needed, compare it to the markup guide in Handout 3. Do you see how the structure of the rendered file is encoded in the Markdown tags? (Remember, click the Preview tab at the top of the window to switch from Code to Preview modes.)
    • Look for a section you want to edit. Make some changes, commit the file to your local repository, then see how your changes look using Preview mode.

Writing Tips and Tricks

  • Always start Markdown pages with a Level 1 header that is the title of the document. I reserve the Level 1 header just for that purpose.
  • It is tempting to remove spaces between lines of text in .md files. BAD idea! Markdown relies on blank lines to keep track of blocks of text. When Markdown is rendered, extra blank lines are deleted automatically.
  • When editing inside GitHub, pages may extend beyond the screen. If so, look at the upper right of the editor window for a drop-down that says No wrap. Click it and choose Soft wrap. This keeps sentences and paragraphs from running off the right side of the screen.


Exercise 3: Updating Your Local and Master Copies of the Resource Guide

Background

You have edited and saved your .md files locally. Now the local repository on your computer is ahead of the version in your GitHub account! In this exercise we’ll synchronize the two repositories by pulling and pushing files between them.

GitHub has two functions that help you keep repositories in sync: pull (sometimes called fetch) and push. These commands can be confusing, but they are at the heart of what makes GitHub so powerful.

When you pull (or, fetch) a copy of a repository, GitHub compares the versions of the files in the repository on its servers and your local computer. If the server version does not match the local version exactly, GitHub will try to download the newer version and update the older version on your local computer. If there are newer versions in BOTH locations, GitHub will ask you to pick one to be the new “correct” version.

Say you have been editing several .md files using the text editor on your computer. When you commit the files, you are telling GitHub “these are the newest versions, and what everyone should be using from now on.” GitHub dutifully stamps them with a time and location code, and stores them locally. You need to push the files to tell the main GitHub server to update its copies.

When you push files, the server compare its copy of each file to the data stamp on the one you pushed. If there are changes in the server copy that are not in yours, GitHub will stop and tell you that you need to pull the changes already logged by the server and merge them with your local changes first. Then you can push the newest version of each file back to the server. This is a quirk of GitHub; usually pulling from the server resolves any conflicts.

Why does GitHub use so many different commands? Why not just save a file instantly and everywhere, like Google does? If you have ever had someone change a Google document you just finished editing back to what you deleted, you know why. GitHub’s strategy is designed for code writers and editors. There has to be one correct version, and one person with the authority to make the decision what files are correct. Committing a file only saves it to the local copy of the repository you happen to be working in. Pushing a file changes it on the main server, and on all of the forked copies.

Procedure

  1. Open GitHub Desktop. If you are not logged in to your account, do so now.

  2. In the upper left of the work window, click on Current Repository. Pick the ABLE 2022 Workshop. You now should see a list of files that changed. The files you created or edited should be listed.

Setting the repository to synchronize.


  1. In the upper part of the work window, click on Fetch Origin. This issues a Pull command; it pulls information about the server version of the repository and compares the two versions.

  2. You should see a list of files that have changed since they were last saved to your account. Give your update a SHORT name. Then click on Commit to save the changes locally.

Committing changes to your local copy of the files.


  1. To update the copy in your GitHub account, click on Push to origin.

Pushing a copy of your changes to your main GitHub account


  1. If you click on Fetch Origin again, you should get a message saying All files up to date. This means your files in the local copy and the server copy of the repository all match.

Tips and Good Practices

How often should you commit and push? It is up to you, but generally you should commit every 30-60 minutes, or right after you complete major edits. You might only push changes to GitHub once or twice a day, though more often does not hurt anything. It is a good idea to push to GitHub when you finish working for the day.

Why commit so often? GitHub creates a detailed record of every Commit and Push command in your account that includes which files were changed and how. If you are editing a large file or several files and accidentally delete some important text, you can use the repository history to reconstruct the missing pieces. The more often you Commit, the finer grained the record of changes.



Exercise 4: Generating Your Output Documents

Background

In Exercises 1-3 you learned how to create, edit, and manage the Markdown files. Now we are going to create documents with those files.

Markdown is converted to other document formats using Pandoc, a “universal document converter.” It can read many different document file types, then convert one format to another. Some file types get fussy when converted, but Markdown and Pandoc play very nicely together.

There are several ways to access Pandoc. You will be using a standalone web-based converter to create clean HTML, and using R Studio to create MS Word documents. I will demonstrate two other routes: using the command line to build single files, and using R Studio’s bookdown package to compile single files into an e-book.

Converting Text.md to Text.html

Many plain text editors (though oddly, not R Studio) can convert Markdown to very compact plain HTML. If your text editor does not have this feature, this web-based Pandoc converter works well.

  1. Go to the MD to HTML Converter at https://ashkanph.github.io/md-to-html/.

  2. In the upper right corner, use Browse to find your local GitHub folder, and choose one of your recently edited .md files.

  3. The .md file will be converted to .html and displayed.

  4. Use the Save as HTML button to write a copy of the file in .html back to your local GitHub repository.

  5. If you open the version of the file with the .html extension in your plain text editor, you will see it has been rewritten using HTML markup. You can copy and paste the HTML code into most LMS pages. Alternatively, you can share the file itself with others; they can open it in any web browser.

Why not use R Studio for HTML? When R Studio generates a standalone HTML preview, it embeds the raw code for every image plus a LOT of extra styling code. For example, the HTML file for the handouts for this workshop that was generated using the Ashkanph converter was 63 Kb. The same HTML file generated using R Studio was 6 Mb. This problem goes away when R Studio creates books; the HTML files are very compact, because they reference separate styling and image files rather than embedding them.

There are many free converters available. Another very good one is Markdown It, which has a very user-friendly interface, but requires copy/pasting the text rather than choosing a file. Dillinger shows the Markdown code in a window next to either the HTML code or the styled text. Rendered Markdown can be exported as HTML, but like R Studio, Dillinger includes some extra styling information.

Converting Text.md to Text.docx

R Studio is very good for converting .md files to well-formatted Word documents.

  1. Open R Studio, and go to the workshop files. Open one of the files you edited or created.

  2. At the top of the screen, open the pulldown menu next to Preview and choose Word document.

Converting Markdown to Word format


  1. R Studio will call Pandoc, generate a pre-formatted MS Word .docx file, then save it to the same directory where the .md file is located.

  2. Click on the .docx file to open it in MS Word.

MS Word files are formatted based on a standard template. To format documents a different way, create a template file with the header and text styles that you want. When newly generated documents are copy/pasted into the template file, the text will change to the styles you set.

Demonstration 1: Running Pandoc From the Command Line

It is very easy to install and run Pandoc from your computer’s command line, and it generates both .docx and .html files. If you would like to try it yourself:

  1. Go to the Pandoc installation page for instructions to download and install to your computer.

  2. Use the following Terminal commands to convert from .md to .html or .docx format. The commands are the same, except for the extension on the output file.

pandoc -s /filepath/Input_Filename.md -o /filepath/Output_Filename.html

pandoc -s /filepath/Input_Filename.md -o /filepath/Output_Filename.docx

Pandoc is fussier about rendering PDFs. First, it does not tolerate markup errors, and may refuse to convert a file. Second, you must install a pdf-engine then call it in the command. Look at the example below:

pandoc -s --pdf-engine=xelatex /filepath/Input_Filename.md -o /filepath/Output_Filename.pdf

The pdf-engine defines what the format will look like. This particular PDF engine’s default layout and fonts look outdated and can be hard to read. Changing them requires some deeper coding work, which is why I do not recommend using Pandoc for creating occasional PDFs. It is quicker to render a file in MS Word then save it as a PDF.

Demonstration 2: Using Bookdown to Compile Documents Into Books

R has powerful libraries for creating online materials. The bookdown package (which uses knitr and Pandoc) combines individual .md files into full length technical books. The Home page for the R Bookdown package has examples of books that were created this way.

There is not enough time for you to set up your own GitHub-hosted book from start to finish. Instead, we’ll take a short tour through the back end of the SWP Writing Resource Guide and see how R Studio can convert a collection of separate .md files into an integrated book.

We also will talk about what is missing from the Resource Guide that you added, and your suggestions for improving it.

Next Steps

Today’s exercises introduced you to most of the tools you need to start using Markdown. If you want to try building your own online book, go to our Bookdown Demo repository, which is an unmodified fork of the original demo by bookdown’s creator, Yihui Yue. Clone this to a new repository, and you have a complete operating skeleton for a book. Authoring Books and Technical Documents With R Markdown describes how to customize it as you desire.

Two other books that can help you continue developing your skills are:

If you want to use our Writing Resource Guide in your own courses, you now have the original documents in your GitHub repository, and all the tools you need to edit it to suit your program needs. If you are interested in writing new material or helping us expand the Guide, let us know.



Information About the Presentation

Equipment Needed

Participants will need to have a laptop that can connect to the internet, and access to a web connection. Tablets are not going to work; GitHub Desktop does not work as an app. It may be helpful to have 2-3 loaner laptops in the event someone only has a tablet.

The workshop can be conducted in a computer lab, but it would be better if participants used their own computers, so they leave with the full set-up needed to continue using the materials at home.

Notes for the Instructor

I plan to use this section to summarize feedback and answer questions received during the workshops. Topics I expect will be covered here includes:

  • Technical issues: potential bottlenecks or challenges in converting files; other formats; proprietary software options.
  • Pedagogical issues: the topics that instructors think are needed in the Resource Guide; questions about the writing instructional strategy used.
  • Suggestions for improvement from the participants.

Sample Results

The working template version of the Resource Guide that participants will clone to their own accounts for editing, a copy of the .md file used to create the handouts, and all other files for the workshop will be available from the workshop’s public GitHub repository.

Flow of the Workshop

Participants will learn to use Markdown, GitHub and GitHub Desktop, and Pandoc text converter in the context of a collaborative writing project.

Markdown is a lightweight but very versatile text markup language that lets authors write well-structured texts once then reuse them multiple ways. It is extremely easy to learn (<20 minutes for 90% of what you will use routinely), and text with Markdown tags remains easy to read. I estimate that >80% of the new materials I write now start out in Markdown.

There are several “flavors” of the original Markdown language standard. I chose the GitHub “flavor” of Markdown (GHFM) for the workshop because:

  • GHFM adds functions that other flavors do not have.
  • There are multiple tools for converting GHFM into other formats.
  • GHFM is nearly identical to the Markdown syntax used by R Studio to write online books.
  • GHFM is the lingua franca for GitHub.

GitHub is best known as a place where data scientists share code, but it works equally well as a no/low cost, secure project space that operates seamlessly between institutions. GitHub also is becoming a destination for hosting blogs, static websites, and open-access book projects.

Many ABLE members already know R and R Studio, but likely think of them more as a platform for statistics and numerical data analysis. When combined with GitHub and Markdown, R Studio becomes a powerful text editor, integrated development environment, and project management space.

Prior to the workshop, participants will register for a free GitHub account and connect GitHub Desktop to their GitHub account. They also will install R and R Studio. These installations are straightforward, but in the event participants have trouble, they can work with a partner while we complete their setup in the first few minutes of the workshop.

During the first 60 minutes of the workshop, participants will copy the text files for the Writing Resource Guide from a sandboxed repository I have set up for this workshop to their personal GitHub accounts. Using both R Studio and a plain text editor, they will edit an existing page, then create a new page for a topic they think is needed. By break time, participants will have completed their writing and saved their modified files back to their personal accounts.

After the break (assuming 30 minutes), participants will spend the next 60 minutes converting their edited Markdown pages into well-structured documents. They will learn to generate files in two formats:

There is not enough time to set up a complete GitHub-hosted book. Instead, I will use the remaining ~30 minutes to demonstrate how R Studio’s knitr and bookdown R libraries can compile individually edited pages into a GitHub-hosted e-book.

Participants will leave with a complete copy to our Science Writing Resource Guide which they can use in their courses. Their computer will be set up and ready to use GitHub Desktop and R Studio to continue editing their copy of the Guide, and they will have a GitHub account that they can use to build books or share pages with others. They also will have the resources needed to convert their work into MS Word or HTML documents.